import { Link, Warning } from '@brillout/docpress'

A recurring problem when doing <Link href="/ssr">SSR</Link> are so-called *hydration mismatches*.

## Hydration mismatch

> What hydration means is explained at <Link href="/hydration" />

A hydration mismatch is when the content rendered to HTML on the server isn't the same as the content rendered in the browser.

Hydration mismatches can induce performance degradations and bugs and should therefore be avoided.

### Vue

Upon a hydration mismatch, Vue throws following errors in the browser:

```
[Vue warn]: Hydration text mismatch:
 - Client: "some content"
 - Server: "some other content"
   at <SomeComponent>
   at <App>
```
```
Hydration completed but contains mismatches.
```

### React

Upon a hydration mismatch, React throws following errors in the browser:

```
Warning: Text content did not match. Server: "some content" Client: "some other content"
```
```
An error occurred during hydration. The server HTML was replaced with client content in <SomeComponent>.
```
```
Text content does not match server-rendered HTML.
```
```
Hydration failed because the initial UI does not match what was rendered on the server.
```
```
There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
```


## Example

This component causes a hydration mismatch because the milliseconds rendered to HTML (e.g. `<span>123</span>`) won't match the milliseconds rendered in the browser (e.g. `<span>167</span>`).

```jsx
<span>{ new Date().getMilliseconds() }</span>
```


Instead, to prevent the hydration mismatch:

```js
export { onBeforeRender }

async function onBeforeRender() {
  const milliseconds = new Date().getMilliseconds()
  return {
    pageContext: {
      milliseconds
    }
  }
}
```
```jsx
<span>{ pageContext.milliseconds }</span>
```

The `pageContext.milliseconds` value is set exactly once, which means that the milliseconds value is the same when rendered to HTML on the server-side and when hydrated in the browser.


## Common causes & solutions

Common causes:
 - **Rendered content is actually different**. Make sure your components render the same content when rendered to HTML on the server-side and when rendered/hydrated on the client-side.
   > See [example](#example) above.
 - **Proxies**: Make sure your proxies don't apply problematic HTML transformations. For example, most HTML minifiers cause hydration mismatches and have to be disabled.
   > If you use Cloudflare, you have to disable Cloudflare's automatic HTML minifier.
 - **Browser cache**: Your browser's cache may load cached & outdated JavaScript, which may cause hydration mismatches if a component is outdated on the client-side and renders something else than the up-to-date component on the server-side. Clear your browser cache and try again.
    > In principle, this shouldn't happen since Vite always busts the browser cache whenever a file is changed. If you get issues with hydration mismatches related to browser caching, then let us know and we'll look into it.

With React:
 - **Old React versions** are buggy around stitching text segments leading to `Warning: Text content did not match`. Update to `react@18.2.0` or above.


## Suppress Hydration Mismatch

For situations where mismatches are inevitable or difficult to avoid, you can silence the hydration mismatch warning.

<Warning>Don’t overuse it: for less potential bugs and for (slightly or significant) better performance, it's best to avoid hydration mismatches if you can.</Warning>

### React

Use the `suppressHydrationWarning` attribute:

```jsx
function SomeComponent() {
  return (
    <span suppressHydrationWarning={true}>
      Current Date: {new Date().toLocaleDateString()}
    </span>
  )
}
```

See:
- [React Docs > hydrate > Suppressing unavoidable hydration mismatch errors](https://react.dev/reference/react-dom/hydrate#suppressing-unavoidable-hydration-mismatch-errors)
- [StackOverflow > Is there any way to avoid "Text content did not match" warning in SSR with React?](https://stackoverflow.com/questions/53959948/is-there-any-way-to-avoid-text-content-did-not-match-warning-in-ssr-with-react/68438131)

### Vue

Use the `data-allow-mismatch` attribute:

```vue
<div data-allow-mismatch="text">{{ data.toLocaleString() }}</div>
```

See:
- [Vue Docs > Server-Side Rendering API > `data-allow-mismatch`](https://vuejs.org/api/ssr.html#data-allow-mismatch)
- [StackOverflow > [Vue][SSR] Suppress hydration mismatch warning](https://stackoverflow.com/questions/68438016/vuessr-suppress-hydration-mismatch-warning/68438108)
